…se verification (#28756)

* docs: add self-hosting troubleshooting guide

Add a dedicated troubleshooting page (docs/self-hosting/troubleshooting.mdx)
covering the most common self-hosting issues:

- 500 error during onboarding caused by missing STRIPE_PRIVATE_KEY (#25993)
- Redirect to localhost after deployment (NEXTAUTH_URL / NEXT_PUBLIC_WEBAPP_URL) (#21921)
- API v2 service not starting in Docker (missing REDIS_URL, JWT_SECRET, WEB_APP_URL)
- CLIENT_FETCH_ERROR in Docker logs
- SSL issues behind a reverse proxy
- Prisma user creation failure on first setup

Also adds the new page to the "Getting Started" navigation group in docs/docs.json.

Co-Authored-By: Paperclip <noreply@paperclip.ing>

* fix(docs): provide safer SSL troubleshooting alternatives

Replace the blanket NODE_TLS_REJECT_UNAUTHORIZED=0 recommendation
with three options in order of preference:
1. Use HTTP internally with proper header forwarding
2. Add internal CA to NODE_EXTRA_CA_CERTS
3. Disable TLS verification (last resort with security warning)

The previous guidance could expose users to MITM attacks on all
external API calls (Stripe, Google, etc.).

* fix(docs): correct NEXTAUTH_URL guidance to prevent OAuth breakage

The previous guidance recommended setting NEXTAUTH_URL to localhost
for SSL/DNS issues, which breaks OAuth callbacks since external
providers would redirect to localhost instead of the public domain.

- Replace localhost workaround with extra_hosts in docker-compose
- Add nginx proxy header configuration example
- Add warnings explaining why localhost breaks OAuth

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix(docs): correct troubleshooting guide based on codebase verification

- Stripe section: Rewrite to accurately reflect current behavior (app
  gracefully handles missing keys by marking Stripe as 'not installed'
  rather than crashing). Clarify that NEXT_PUBLIC_STRIPE_PUBLIC_KEY
  belongs in .env.appStore.
- API v2 section: Add missing required vars (STRIPE_API_KEY,
  STRIPE_WEBHOOK_SECRET, NEXTAUTH_SECRET) that crash the service if
  absent. Move WEB_APP_URL to optional (it has a fallback default).
- CLIENT_FETCH_ERROR section: Add caveat about HTTPS URLs failing
  with the extra_hosts approach when app listens on port 3000.
- Vercel note: Clarify that NEXTAUTH_URL is auto-inferred via
  VERCEL_URL, not just 'left empty'.
- Database section: Replace unverifiable metadata/id advice with
  actionable migration and setup guidance matching actual code in
  apps/web/app/api/auth/setup/route.ts.

Co-Authored-By: romitgabani1 <romitgabani1.work@gmail.com>

* docs: fix inaccuracies in self-hosting troubleshooting guide

- Add missing CALENDSO_ENCRYPTION_KEY to API v2 required variables
- Fix setup endpoint path from /api/auth/setup to /auth/setup
- Add note about NEXTAUTH_URL auto-derivation from NEXT_PUBLIC_WEBAPP_URL

* fix(docs): correct NEXTAUTH_URL derivation mechanism description

NextAuth infers the base URL from the request's Host header when
NEXTAUTH_URL is not set, not from NEXT_PUBLIC_WEBAPP_URL directly.

Co-Authored-By: romitgabani1 <romitgabani1.work@gmail.com>

---------

Co-authored-by: shockzM1 <shockz@dsn.so>
Co-authored-by: Paperclip <noreply@paperclip.ing>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>